Crate faer_core

faer is a linear algebra library for Rust, with a focus on high performance for medium/large matrices.

The core module contains the building blocks of linear algebra:

• Matrix structure definitions: Mat, MatRef, and MatMut.
• Coefficient-wise matrix operations, like addition and subtraction: either using the builtin + and - operators or using the low level api zipped!.
• Matrix multiplication: either using the builtin * operator or the low level mul module.
• Triangular matrix solve: the solve module.
• Triangular matrix inverse: the inverse module.
• Householder matrix multiplication: the householder module.

Example

use faer_core::{mat, scale, Mat};

let a = mat![
    [1.0, 5.0, 9.0],
    [2.0, 6.0, 10.0],
    [3.0, 7.0, 11.0],
    [4.0, 8.0, 12.0f64],
];

let b = Mat::<f64>::from_fn(4, 3, |i, j| (i + j) as f64);

let add = &a + &b;
let sub = &a - &b;
let scale = scale(3.0) * &a;
let mul = &a * b.transpose();

Entity trait

Matrices are built on top of the Entity trait, which describes the prefered memory storage layout for a given type E. An entity can be decomposed into a group of units: for a natively supported type (f32, f64, c32, c64), the unit is simply the type itself, and a group contains a single element. On the other hand, for a type with a more specific preferred layout, like an extended precision floating point type, or a dual number type, the unit would be one of the natively supported types, and the group would be a structure holding the components that build up the full value.

To take a more specific example: num_complex::Complex<f64> has a storage memory layout that differs from that of c64 (see complex_native for more details). Its real and complex components are stored separately, so its unit type is f64, while its group type is Complex. In practice, this means that for a Mat<f64>, methods such as Mat::col_as_slice will return a &[f64]. Meanwhile, for a Mat<Complex<f64>>, Mat::col_as_slice will return Complex<&[f64]>, which holds two slices, each pointing respectively to a view over the real and the imaginary components.

While the design of the entity trait is unconventional, it helps us achieve much higher performance when targetting non native types, due to the design matching the typical preffered CPU layout for SIMD operations. And for native types, since Group<T> is just T, the entity layer is a no-op, and the matrix layout is compatible with the classic contiguous layout that’s commonly used by other libraries.

Memory allocation

Since most faer crates aim to expose a low level api for optimal performance, most algorithms try to defer memory allocation to the user.

However, since a lot of algorithms need some form of temporary space for intermediate computations, they may ask for a slice of memory for that purpose, by taking a stack: PodStack parameter. A PodStack is a thin wrapper over a slice of memory bytes. This memory may come from any valid source (heap allocation, fixed-size array on the stack, etc.). The functions taking a PodStack parameter have a corresponding function with a similar name ending in _req that returns the memory requirements of the algorithm. For example: householder::apply_block_householder_on_the_left_in_place_with_conj and householder::apply_block_householder_on_the_left_in_place_req.

The memory stack may be reused in user-code to avoid repeated allocations, and it is also possible to compute the sum (dyn_stack::StackReq::all_of) or union (dyn_stack::StackReq::any_of) of multiple requirements, in order to optimally combine them into a single allocation.

After computing a dyn_stack::StackReq, one can query its size and alignment to allocate the required memory. The simplest way to do so is through dyn_stack::GlobalMemBuffer::new.

Re-exports

• pub use matrix_ops::scale;
• pub use dyn_stack;
• pub use reborrow;
• pub use faer_entity::pulp;
• pub use complex_native::*;

Modules

• col
  Column view creation module.
• complex_native
  Native complex floating point types whose real and imaginary parts are stored contiguously.
• constrained
  Advanced: Module for index and matrix types with compile time checks, instead of bound checking at runtime.
• group_helpers
  Advanced: Helper types for working with GroupFor in generic contexts.
• householder
  Block Householder transformations.
• inner
  Specialized containers that are used with Matrix.
• inverse
  Triangular matrix inversion.
• mat
  Matrix view creation module.
• matrix_ops
  addition and subtraction of matrices
• mul
  Matrix multiplication.
• permutation
  Permutation matrices.
• row
  Row view creation module.
• serde_impl
  Serde implementations for Mat
• solve
  Triangular solve module.
• sparse
  Sparse matrix data structures.
• zip
  Implementation of zipped! structures.

Macros

• col
  Creates a Col containing the arguments.
• concat
  Concatenates the matrices in each row horizontally, then concatenates the results vertically. concat![[a0, a1, a2], [b1, b2]] results in the matrix
• mat
  Creates a Mat containing the arguments.
• row
  Creates a Row containing the arguments.
• unzipped
  Used to undo the zipping by the zipped! macro.
• zipped
  Zips together matrix of the same size, so that coefficient-wise operations can be performed on their elements.

Structs

• IdentityGroup
• Matrix
  Generic matrix container.

Enums

• Conj
  Whether a matrix should be implicitly conjugated when read or not.
• FaerError
  Errors that can occur in sparse algorithms.
• Parallelism
  Parallelism strategy that can be passed to most of the routines in the library.
• Side
  Specifies whether the triangular lower or upper part of a matrix should be accessed.

Traits

• As2D
  Trait for types that can be converted to a 2D matrix view.
• As2DMut
  Trait for types that can be converted to a mutable 2D matrix view.
• AsColMut
  Trait for types that can be converted to a mutable col view.
• AsColRef
  Trait for types that can be converted to a column view.
• AsMatMut
  Trait for types that can be converted to a mutable matrix view.
• AsMatRef
  Trait for types that can be converted to a matrix view.
• AsRowMut
  Trait for types that can be converted to a mutable row view.
• AsRowRef
  Trait for types that can be converted to a row view.
• ColIndex
  Represents a type that can be used to slice a column, such as an index or a range of indices.
• ComplexField
  Unstable trait containing the operations that a number type needs to implement.
• Conjugate
  Trait for types that may be implicitly conjugated.
• Entity
  Unstable core trait for describing how a scalar value may be split up into individual component.
• MatIndex
  Represents a type that can be used to slice a matrix, such as an index or a range of indices.
• RealField
  Unstable trait containing the operations that a real number type needs to implement.
• RowIndex
  Represents a type that can be used to slice a row, such as an index or a range of indices.
• SimdCtx
• SimpleEntity

Functions

• disable_global_parallelism
  Causes functions that access global parallelism settings to panic.
• get_global_parallelism
  Gets the global parallelism settings.
• kron
  Kronecker product of two matrices.
• set_global_parallelism
  Sets the global parallelism settings.
• temp_mat_constant
  Creates a temporary matrix of constant values, from the given memory stack.
• temp_mat_req
  Returns the stack requirements for creating a temporary matrix with the given dimensions.
• temp_mat_uninit
  Creates a temporary matrix of untouched values, from the given memory stack.
• temp_mat_zeroed
  Creates a temporary matrix of zero values, from the given memory stack.

Type Aliases

• Col
  Heap allocated resizable column vector.
• ColMut
  Mutable view over a column vector, similar to a mutable reference to a strided slice.
• ColRef
  Immutable view over a column vector, similar to an immutable reference to a strided slice.
• GroupFor
• Mat
  Heap allocated resizable matrix, similar to a 2D Vec.
• MatMut
  Mutable view over a matrix, similar to a mutable reference to a 2D strided slice.
• MatRef
  Immutable view over a matrix, similar to an immutable reference to a 2D strided slice.
• MatScale
  Wrapper around a scalar value that allows scalar multiplication by matrices.
• Row
  Heap allocated resizable row vector.
• RowMut
  Mutable view over a row vector, similar to a mutable reference to a strided slice.
• RowRef
  Immutable view over a row vector, similar to an immutable reference to a strided slice.